package nevo.core;

import java.util.List;
import java.util.Map;

/**
 * Implementations of this class take a {@link Model}
 * and a list of name-value pair inputs as initial guesses,
 * then computes a better guess using the iterate(...)
 * function. Usage:
 * <pre>
 *  //create model and objective function
 *  Model m = new SomeModelImplementation();
 *  ObjectiveFunction func = new SomeObjectiveFunction();
 *  
 *  //create initial guess
 *  Map&lt;String,Object&gt; initialGuess = new Map&lt;String,Object&gt;();
 *  initialGuess.put("x", &lt;some value&gt;);
 *  List&lt;Map&lt;String,Object&gt;&gt; guessList = new ArrayList&lt;Map&lt;String,Object&gt;&gt;();
 *    
 *  //make optimizer and set necessary values
 * 	Optimizer o = new SomeOptimizerImplementation();
 *  o.setModel(m);
 *  o.setObjectiveFunction(func);
 *  o.setInitialGuesses(guessList);
 *  
 *  //iterate a 100 times
 *  try {
 *    IRecord irec = null;
 *  	for (int k = 0; k &lt; 100; k++) irec = o.iterate(irec);
 *  } catch (Exception e) {
 *    e.printStackTrace(System.err);
 *  } 
 * </pre>
 * @author mschachter
 *
 */
public interface Optimizer
{
	public Model getModel();
	public void setModel(Model m);
	
	public void  setObjectiveFunction(ObjectiveFunction func);
	public ObjectiveFunction getObjectiveFunction();	
	
	/**
	 * Set the list of initial guesses. Some optimizers only require a
	 * single initial guess, like Newton's method (not yet implemented).
	 * Other optimizers, such as Evolutionary Strategies, require multiple
	 * initial guesses to seed their parent population.
	 * @param params A List of initial guesses that the {@link Model} and
	 * 		  {@link ObjectiveFunction} understand.
	 * @throws Exception
	 */
	public void setInitialGuesses(List< Map<String,Object> > params) throws Exception;
   
	public List<IRecord> getCurrentEstimates() throws Exception;
	public IRecord iterate(IRecord previrec) throws Exception;
	
}
